Azure DevOps rejects any protocol-v0 upload-pack request whose capability
list omits multi_ack, with HTTP 400 "TF401041: Clients must support
multi-ack." go-git v5 keeps MultiACK and MultiACKDetailed in
transport.UnsupportedCapabilities and deletes them from the server's
advertisement as it parses, so the capability is never requested and every
fetch against ADO fails (#288).

v6 implements the capability (go-git#1204), and upstream then deleted their
own ADO workaround example saying it "works out of the box". This takes
v6.0.0-alpha.5 -- the latest tag, and identical to upstream main -- rather
than PR #292's fallback to a bundled system git binary, which measured at
+723 MB of image and left the CRITICAL image-scan gate blind to git,
OpenSSH and OpenSSL because they arrive as loose files with no package
database. The reasoning, the measurements and the four options are in
docs/design/azure-devops-multi-ack.md.

The blast radius of the ADO problem is one call, repo.Fetch. CheckRepo and
listRemoteRefs read only the ref advertisement, and PushAtomic speaks
receive-pack, which has no multi_ack at all. The tests assert exactly that,
and they passed on v5.

Red-first, and it needs no Azure DevOps tenant: canonical git's own
upload-pack advertises multi_ack, so git-http-backend behind a proxy that
enforces ADO's rule is a faithful simulator for both halves -- the proxy
reproduces the rejected request, the real backend reproduces the multi-ACK
response v5 also cannot parse. The v2 opt-in header is stripped so a
v2-capable client cannot sidestep the capability under test.
TestADO_SmartFetch_RequiresMultiAck fails on v5 with ADO's exact 400 and
passes on v6.

The API migration:

  - transport.AuthMethod is gone; auth is functional options. A credential
    now travels as []gitclient.Option, and git.Credential keeps the
    concrete value alongside so the Secret-key-to-auth-field mapping stays
    assertable -- the options are closures and cannot be inspected.
  - transport.NewEndpoint + client.NewClient + NewReceivePackSession
    become transport.ParseURL + gitclient.New(opts).Handshake.
  - AdvertisedReferences becomes GetRemoteRefs, returning a slice.
  - ReceivePack becomes Session.Push.

The atomic push keeps its guarantee unchanged: one session serves both the
advertisement and the push, and PushRequest.Commands takes the same
*packp.Command, so the server-side Old/New compare-and-swap is verbatim.
v6 negotiates report-status itself and returns a rejected command as the
error from Push, so the separate status inspection collapses into one
check, and Atomic is now a first-class field.

Two settings v6 reads from the environment that v5 ignored, both failing
closed, and neither visible to a unit test:

  - commit.gpgSign, merged across system, global and local scope, is
    consulted whenever CommitOptions.Signer is nil, and refuses the commit
    when set with no signer registered. Any host or image with it set
    would break every commit we make. PinExplicitSigningPolicy writes the
    local value false at init: our signing policy comes from the
    GitProvider, not from ambient config.
  - HostKeyAlgorithms is derived by reading ~/.ssh/known_hosts and
    /etc/ssh/ssh_known_hosts whenever ClientConfig returns it empty, even
    when a HostKeyCallback was supplied, and hard-fails when neither file
    exists. The controller image is distroless with neither, so every SSH
    remote would have failed in production regardless of the credential.
    ssh.KeyAuth now always populates the list, from the pinned known_hosts
    when there is one and a modern default set otherwise. Found by the e2e
    suite against a real Gitea; no unit test can reach it, because the
    fallback lives in the transport's connect rather than in ClientConfig.

TestBranchWorker_ConcurrentOperations moves to a real git server. v5's
file:// transport spawned the real git-receive-pack; v6 runs go-git's
in-process one, whose updateReferences never compares cmd.Old and just
sets the reference, so over file:// every racing push wins and the test
was passing vacuously with 2 commits instead of 4. Any future test of the
compare-and-swap must avoid file://.

Closes #288
Refs #292

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…address the review

Four review findings, all real:

  - PrepareBranch pinned the signing policy only on repositories it CREATED.
    Worker clones live on a volume across restarts, and a repository made
    before the pin existed is the common case on upgrade -- either would hit
    go-git v6's "cannot auto-sign commit" the first time an ambient
    commit.gpgSign is true. The pin now covers the reuse path too, which is
    where it matters most.
  - getPushSession indexed remote.Config().URLs[0] unguarded. go-git rejects
    a URL-less remote in its own validation, but a hand-edited .git/config
    can still present one, and indexing it panics rather than fails.
  - The pinned-known_hosts subtest could not tell a pin hit from the default
    fallback, because the default set also carries the RSA algorithms. It now
    asserts the list is narrower than the default and excludes ed25519, which
    only the pin can produce.
  - docs/INDEX.md still said "decision needed" after the design record moved
    to decided-and-built, and undercounted its own list by one.

Separately, and found by porting #292's Azure DevOps examples: the credential
those examples document did not work. ADO sends a PAT as HTTP basic auth with
the token as the password and ignores the username, so its documented Secret
carries an empty username -- and firstSecretValue treats an empty value as an
absent key, so the basic-auth branch never fired and the Secret was refused
with "does not contain valid authentication data". Pre-existing on v5 too.
The password is what carries the credential, so it is what we branch on now. A
username with no password stays an error, because that one is a real mistake.

Verified against a real Azure DevOps repository, which is what the new opt-in
tests are for. Both skip themselves without a credential, so CI is unchanged:

  - internal/git/ado_live_test.go walks the branch-resolution contract against
    the real remote in the order the code implements it -- empty repository
    resolves to nothing, an absent target falls back to the default, a present
    target wins while the default is still fetched as a safety net -- and ends
    on the negotiating fetch, the one request go-git v5 cannot make.
  - test/e2e/ado_e2e_test.go proves the operator mirrors a live ConfigMap into
    a real ADO repository. It reads the result back with canonical git rather
    than our own library, so the assertion does not depend on the code under
    test.

docs/azure-devops-getting-started.md is written from that e2e recipe, and says
plainly why the connectivity check can pass on a release where every fetch
fails: the advertisement is a different request that never needed multi_ack.

Refs #288

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

… at a time

I probed ADO with a bare `want <sha>` carrying no capability list, got HTTP
200, and concluded that the six-year-old bug reports were wrong. They are not.
That shape is the one row ADO accepts, and no real client sends it. Running
go-git v5.19.1 against the same repository reproduced the reported failure
immediately -- and not on a fetch, on the CLONE:

  CLONE FAILED: unexpected client error: unexpected requesting
  ".../git-upload-pack" status code: 400

The rule, measured one request shape at a time against a real repository:

  want <sha>                                        -> 200
  want <sha> side-band-64k ofs-delta agent=...      -> 400 TF401041
  want <sha> side-band-64k                          -> 400 TF401041
  want <sha> agent=git/2.39.5                       -> 400 TF401041
  want <sha> multi_ack side-band-64k ofs-delta      -> 200
  want <sha> multi_ack_detailed side-band-64k       -> 200

So the trigger is a capability list that omits multi_ack, not the absence of
negotiation, and either capability satisfies it. v5 filters both out of the
advertisement before deciding what to ask for, so every request it sends is
the rejected shape.

The doc keeps the wrong turn rather than quietly correcting it, because the
failure mode is worth naming: probing with a hand-rolled request tests the
request you built, not the behaviour you are attributing to it, and
contradicting a long-standing external bug report needs a reproduction with
the real client rather than a curl that disagrees.

Also records what canonical git advertises (which is why it never notices this
at all, and why git-http-backend is a usable stand-in), that receive-pack has
no multi_ack whatsoever so pushing was never affected on any version, and the
sources behind each claim.

TestADOLive_StillRequiresMultiAck turns the premise into a canary: it asserts
ADO STILL rejects the capability-list-without-multi_ack shape, and fails loudly
with "GOOD NEWS, NOT A BUG" if Microsoft ever fixes it. Verified against the
real server, which answers:

  TF401041: The Git protocol sent is not as expected (Clients must support
  multi-ack.).

The public-fixture idea is dropped -- Azure DevOps no longer allows new public
projects -- so the live tests stay opt-in and PAT-gated, and never run in CI.
E2E_ADO_EMPTY_REPO_URL names a repository that stays empty, which is the only
way to cover the empty-repository contract more than once: the main fixture
seeds itself on first run.

Refs #288

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

configuration.md had grown a full Azure DevOps walkthrough inline -- the Secret,
the GitProvider, Entra, SSH, and the multi_ack background -- duplicating
azure-devops-getting-started.md a screen below the GitProvider example.
github-setup-guide.md already establishes the pattern: per-provider setup is its
own page, and configuration.md points at it.

So the section goes, and what stays is the single thing that surprises people,
placed where it bites: a note under the credentials-Secret auth-keys table,
which is exactly where a reader learns HTTP basic means username + password and
needs to know Azure DevOps is the exception that carries only a password.

Also wires E2E_ADO_EMPTY_REPO_URL through the getting-started guide, and names
TestADOLive_StillRequiresMultiAck as a canary there, so someone hitting a red
build knows a failure means Microsoft fixed their end rather than that something
broke.

Verified against the real fixtures at dev.azure.com/configbutler/tests: all four
live tests pass, including the empty-repository case against a repository that
stays empty and the canary, which reports

  TF401041: The Git protocol sent is not as expected (Clients must support
  multi-ack.).

and the operator-level e2e spec mirrors a live ConfigMap into the repository
(1 passed, 0 failed).

Refs #288

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>